home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / ft.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  17.8 KB  |  634 lines
  1. /**
  2.  * @file ft.h File Transfer API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  *
  25.  * @see @ref xfer-signals
  26.  */
  27. #ifndef _PURPLE_FT_H_
  28. #define _PURPLE_FT_H_
  29.  
  30. /**************************************************************************/
  31. /** Data Structures                                                       */
  32. /**************************************************************************/
  33. typedef struct _PurpleXfer PurpleXfer;
  34.  
  35. #include <glib.h>
  36. #include <stdio.h>
  37.  
  38. #include "account.h"
  39.  
  40. /**
  41.  * Types of file transfers.
  42.  */
  43. typedef enum
  44. {
  45.     PURPLE_XFER_UNKNOWN = 0,  /**< Unknown file transfer type. */
  46.     PURPLE_XFER_SEND,         /**< File sending.               */
  47.     PURPLE_XFER_RECEIVE       /**< File receiving.             */
  48.  
  49. } PurpleXferType;
  50.  
  51. /**
  52.  * The different states of the xfer.
  53.  */
  54. typedef enum
  55. {
  56.     PURPLE_XFER_STATUS_UNKNOWN = 0,   /**< Unknown, the xfer may be null. */
  57.     PURPLE_XFER_STATUS_NOT_STARTED,   /**< It hasn't started yet. */
  58.     PURPLE_XFER_STATUS_ACCEPTED,      /**< Receive accepted, but destination file not selected yet */
  59.     PURPLE_XFER_STATUS_STARTED,       /**< purple_xfer_start has been called. */
  60.     PURPLE_XFER_STATUS_DONE,          /**< The xfer completed successfully. */
  61.     PURPLE_XFER_STATUS_CANCEL_LOCAL,  /**< The xfer was canceled by us. */
  62.     PURPLE_XFER_STATUS_CANCEL_REMOTE  /**< The xfer was canceled by the other end, or we couldn't connect. */
  63. } PurpleXferStatusType;
  64.  
  65. /**
  66.  * File transfer UI operations.
  67.  *
  68.  * Any UI representing a file transfer must assign a filled-out
  69.  * PurpleXferUiOps structure to the purple_xfer.
  70.  */
  71. typedef struct
  72. {
  73.     void (*new_xfer)(PurpleXfer *xfer);
  74.     void (*destroy)(PurpleXfer *xfer);
  75.     void (*add_xfer)(PurpleXfer *xfer);
  76.     void (*update_progress)(PurpleXfer *xfer, double percent);
  77.     void (*cancel_local)(PurpleXfer *xfer);
  78.     void (*cancel_remote)(PurpleXfer *xfer);
  79.  
  80.     void (*_purple_reserved1)(void);
  81.     void (*_purple_reserved2)(void);
  82.     void (*_purple_reserved3)(void);
  83.     void (*_purple_reserved4)(void);
  84. } PurpleXferUiOps;
  85.  
  86. /**
  87.  * A core representation of a file transfer.
  88.  */
  89. struct _PurpleXfer
  90. {
  91.     guint ref;                    /**< The reference count.                */
  92.     PurpleXferType type;            /**< The type of transfer.               */
  93.  
  94.     PurpleAccount *account;         /**< The account.                        */
  95.  
  96.     char *who;                    /**< The person on the other end of the
  97.                                        transfer.                           */
  98.  
  99.     char *message;                /**< A message sent with the request     */
  100.     char *filename;               /**< The name sent over the network.     */
  101.     char *local_filename;         /**< The name on the local hard drive.   */
  102.     size_t size;                  /**< The size of the file.               */
  103.  
  104.     FILE *dest_fp;                /**< The destination file pointer.       */
  105.  
  106.     char *remote_ip;              /**< The remote IP address.              */
  107.     int local_port;               /**< The local port.                     */
  108.     int remote_port;              /**< The remote port.                    */
  109.  
  110.     int fd;                       /**< The socket file descriptor.         */
  111.     int watcher;                  /**< Watcher.                            */
  112.  
  113.     size_t bytes_sent;            /**< The number of bytes sent.           */
  114.     size_t bytes_remaining;       /**< The number of bytes remaining.      */
  115.     time_t start_time;            /**< When the transfer of data began.    */
  116.     time_t end_time;              /**< When the transfer of data ended.    */
  117.  
  118.     size_t current_buffer_size;   /**< This gradually increases for fast
  119.                                        network connections. */
  120.  
  121.     PurpleXferStatusType status;    /**< File Transfer's status.             */
  122.  
  123.     /* I/O operations. */
  124.     struct
  125.     {
  126.         void (*init)(PurpleXfer *xfer);
  127.         void (*request_denied)(PurpleXfer *xfer);
  128.         void (*start)(PurpleXfer *xfer);
  129.         void (*end)(PurpleXfer *xfer);
  130.         void (*cancel_send)(PurpleXfer *xfer);
  131.         void (*cancel_recv)(PurpleXfer *xfer);
  132.         gssize (*read)(guchar **buffer, PurpleXfer *xfer);
  133.         gssize (*write)(const guchar *buffer, size_t size, PurpleXfer *xfer);
  134.         void (*ack)(PurpleXfer *xfer, const guchar *buffer, size_t size);
  135.  
  136.     } ops;
  137.  
  138.     PurpleXferUiOps *ui_ops;            /**< UI-specific operations. */
  139.     void *ui_data;                    /**< UI-specific data.       */
  140.  
  141.     void *data;                       /**< prpl-specific data.     */
  142. };
  143.  
  144. #ifdef __cplusplus
  145. extern "C" {
  146. #endif
  147.  
  148. /**************************************************************************/
  149. /** @name File Transfer API                                               */
  150. /**************************************************************************/
  151. /*@{*/
  152.  
  153. /**
  154.  * Creates a new file transfer handle.
  155.  * This is called by prpls.
  156.  * The handle starts with a ref count of 1, and this reference
  157.  * is owned by the core. The prpl normally does not need to
  158.  * purple_xfer_ref or unref.
  159.  *
  160.  * @param account The account sending or receiving the file.
  161.  * @param type    The type of file transfer.
  162.  * @param who     The name of the remote user.
  163.  *
  164.  * @return A file transfer handle.
  165.  */
  166. PurpleXfer *purple_xfer_new(PurpleAccount *account,
  167.                                 PurpleXferType type, const char *who);
  168.  
  169. /**
  170.  * Returns all xfers
  171.  *
  172.  * @return all current xfers with refs
  173.  */
  174. GList *purple_xfers_get_all(void);
  175.  
  176. /**
  177.  * Increases the reference count on a PurpleXfer.
  178.  * Please call purple_xfer_unref later.
  179.  *
  180.  * @param xfer A file transfer handle.
  181.  */
  182. void purple_xfer_ref(PurpleXfer *xfer);
  183.  
  184. /**
  185.  * Decreases the reference count on a PurpleXfer.
  186.  * If the reference reaches 0, purple_xfer_destroy (an internal function)
  187.  * will destroy the xfer. It calls the ui destroy cb first.
  188.  * Since the core keeps a ref on the xfer, only an erroneous call to
  189.  * this function will destroy the xfer while still in use.
  190.  *
  191.  * @param xfer A file transfer handle.
  192.  */
  193. void purple_xfer_unref(PurpleXfer *xfer);
  194.  
  195. /**
  196.  * Requests confirmation for a file transfer from the user. If receiving
  197.  * a file which is known at this point, this requests user to accept and
  198.  * save the file. If the filename is unknown (not set) this only requests user
  199.  * to accept the file transfer. In this case protocol must call this function
  200.  * again once the filename is available.
  201.  *
  202.  * @param xfer The file transfer to request confirmation on.
  203.  */
  204. void purple_xfer_request(PurpleXfer *xfer);
  205.  
  206. /**
  207.  * Called if the user accepts the file transfer request.
  208.  *
  209.  * @param xfer     The file transfer.
  210.  * @param filename The filename.
  211.  */
  212. void purple_xfer_request_accepted(PurpleXfer *xfer, const char *filename);
  213.  
  214. /**
  215.  * Called if the user rejects the file transfer request.
  216.  *
  217.  * @param xfer The file transfer.
  218.  */
  219. void purple_xfer_request_denied(PurpleXfer *xfer);
  220.  
  221. /**
  222.  * Returns the type of file transfer.
  223.  *
  224.  * @param xfer The file transfer.
  225.  *
  226.  * @return The type of the file transfer.
  227.  */
  228. PurpleXferType purple_xfer_get_type(const PurpleXfer *xfer);
  229.  
  230. /**
  231.  * Returns the account the file transfer is using.
  232.  *
  233.  * @param xfer The file transfer.
  234.  *
  235.  * @return The account.
  236.  */
  237. PurpleAccount *purple_xfer_get_account(const PurpleXfer *xfer);
  238.  
  239. /**
  240.  * Returns the status of the xfer.
  241.  *
  242.  * @param xfer The file transfer.
  243.  *
  244.  * @return The status.
  245.  */
  246. PurpleXferStatusType purple_xfer_get_status(const PurpleXfer *xfer);
  247.  
  248. /**
  249.  * Returns true if the file transfer was canceled.
  250.  *
  251.  * @param xfer The file transfer.
  252.  *
  253.  * @return Whether or not the transfer was canceled.
  254.  */
  255. gboolean purple_xfer_is_canceled(const PurpleXfer *xfer);
  256.  
  257. /**
  258.  * Returns the completed state for a file transfer.
  259.  *
  260.  * @param xfer The file transfer.
  261.  *
  262.  * @return The completed state.
  263.  */
  264. gboolean purple_xfer_is_completed(const PurpleXfer *xfer);
  265.  
  266. /**
  267.  * Returns the name of the file being sent or received.
  268.  *
  269.  * @param xfer The file transfer.
  270.  *
  271.  * @return The filename.
  272.  */
  273. const char *purple_xfer_get_filename(const PurpleXfer *xfer);
  274.  
  275. /**
  276.  * Returns the file's destination filename,
  277.  *
  278.  * @param xfer The file transfer.
  279.  *
  280.  * @return The destination filename.
  281.  */
  282. const char *purple_xfer_get_local_filename(const PurpleXfer *xfer);
  283.  
  284. /**
  285.  * Returns the number of bytes sent (or received) so far.
  286.  *
  287.  * @param xfer The file transfer.
  288.  *
  289.  * @return The number of bytes sent.
  290.  */
  291. size_t purple_xfer_get_bytes_sent(const PurpleXfer *xfer);
  292.  
  293. /**
  294.  * Returns the number of bytes remaining to send or receive.
  295.  *
  296.  * @param xfer The file transfer.
  297.  *
  298.  * @return The number of bytes remaining.
  299.  */
  300. size_t purple_xfer_get_bytes_remaining(const PurpleXfer *xfer);
  301.  
  302. /**
  303.  * Returns the size of the file being sent or received.
  304.  *
  305.  * @param xfer The file transfer.
  306.  *
  307.  * @return The total size of the file.
  308.  */
  309. size_t purple_xfer_get_size(const PurpleXfer *xfer);
  310.  
  311. /**
  312.  * Returns the current percentage of progress of the transfer.
  313.  *
  314.  * This is a number between 0 (0%) and 1 (100%).
  315.  *
  316.  * @param xfer The file transfer.
  317.  *
  318.  * @return The percentage complete.
  319.  */
  320. double purple_xfer_get_progress(const PurpleXfer *xfer);
  321.  
  322. /**
  323.  * Returns the local port number in the file transfer.
  324.  *
  325.  * @param xfer The file transfer.
  326.  *
  327.  * @return The port number on this end.
  328.  */
  329. unsigned int purple_xfer_get_local_port(const PurpleXfer *xfer);
  330.  
  331. /**
  332.  * Returns the remote IP address in the file transfer.
  333.  *
  334.  * @param xfer The file transfer.
  335.  *
  336.  * @return The IP address on the other end.
  337.  */
  338. const char *purple_xfer_get_remote_ip(const PurpleXfer *xfer);
  339.  
  340. /**
  341.  * Returns the remote port number in the file transfer.
  342.  *
  343.  * @param xfer The file transfer.
  344.  *
  345.  * @return The port number on the other end.
  346.  */
  347. unsigned int purple_xfer_get_remote_port(const PurpleXfer *xfer);
  348.  
  349. /**
  350.  * Sets the completed state for the file transfer.
  351.  *
  352.  * @param xfer      The file transfer.
  353.  * @param completed The completed state.
  354.  */
  355. void purple_xfer_set_completed(PurpleXfer *xfer, gboolean completed);
  356.  
  357. /**
  358.  * Sets the filename for the file transfer.
  359.  *
  360.  * @param xfer     The file transfer.
  361.  * @param message The message.
  362.  */
  363. void purple_xfer_set_message(PurpleXfer *xfer, const char *message);
  364.  
  365. /**
  366.  * Sets the filename for the file transfer.
  367.  *
  368.  * @param xfer     The file transfer.
  369.  * @param filename The filename.
  370.  */
  371. void purple_xfer_set_filename(PurpleXfer *xfer, const char *filename);
  372.  
  373. /**
  374.  * Sets the local filename for the file transfer.
  375.  *
  376.  * @param xfer     The file transfer.
  377.  * @param filename The filename
  378.  */
  379. void purple_xfer_set_local_filename(PurpleXfer *xfer, const char *filename);
  380.  
  381. /**
  382.  * Sets the size of the file in a file transfer.
  383.  *
  384.  * @param xfer The file transfer.
  385.  * @param size The size of the file.
  386.  */
  387. void purple_xfer_set_size(PurpleXfer *xfer, size_t size);
  388.  
  389. /**
  390.  * Sets the current working position in the active file transfer.  This
  391.  * can be used to jump backward in the file if the protocol detects
  392.  * that some bit of data needs to be resent or has been sent twice.
  393.  *
  394.  * It's used for pausing and resuming an oscar file transfer.
  395.  *
  396.  * @param xfer       The file transfer.
  397.  * @param bytes_sent The new current position in the file.  If we're
  398.  *                   sending a file then this is the byte that we will
  399.  *                   send.  If we're receiving a file, this is the
  400.  *                   next byte that we expect to receive.
  401.  */
  402. void purple_xfer_set_bytes_sent(PurpleXfer *xfer, size_t bytes_sent);
  403.  
  404. /**
  405.  * Returns the UI operations structure for a file transfer.
  406.  *
  407.  * @param xfer The file transfer.
  408.  *
  409.  * @return The UI operations structure.
  410.  */
  411. PurpleXferUiOps *purple_xfer_get_ui_ops(const PurpleXfer *xfer);
  412.  
  413. /**
  414.  * Sets the read function for the file transfer.
  415.  *
  416.  * @param xfer The file transfer.
  417.  * @param fnc  The read function.
  418.  */
  419. void purple_xfer_set_read_fnc(PurpleXfer *xfer,
  420.         gssize (*fnc)(guchar **, PurpleXfer *));
  421.  
  422. /**
  423.  * Sets the write function for the file transfer.
  424.  *
  425.  * @param xfer The file transfer.
  426.  * @param fnc  The write function.
  427.  */
  428. void purple_xfer_set_write_fnc(PurpleXfer *xfer,
  429.         gssize (*fnc)(const guchar *, size_t, PurpleXfer *));
  430.  
  431. /**
  432.  * Sets the acknowledge function for the file transfer.
  433.  *
  434.  * @param xfer The file transfer.
  435.  * @param fnc  The acknowledge function.
  436.  */
  437. void purple_xfer_set_ack_fnc(PurpleXfer *xfer,
  438.         void (*fnc)(PurpleXfer *, const guchar *, size_t));
  439.  
  440. /**
  441.  * Sets the function to be called if the request is denied.
  442.  *
  443.  * @param xfer The file transfer.
  444.  * @param fnc The request denied prpl callback.
  445.  */
  446. void purple_xfer_set_request_denied_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
  447.  
  448. /**
  449.  * Sets the transfer initialization function for the file transfer.
  450.  *
  451.  * This function is required, and must call purple_xfer_start() with
  452.  * the necessary parameters. This will be called if the file transfer
  453.  * is accepted by the user.
  454.  *
  455.  * @param xfer The file transfer.
  456.  * @param fnc  The transfer initialization function.
  457.  */
  458. void purple_xfer_set_init_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
  459.  
  460. /**
  461.  * Sets the start transfer function for the file transfer.
  462.  *
  463.  * @param xfer The file transfer.
  464.  * @param fnc  The start transfer function.
  465.  */
  466. void purple_xfer_set_start_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
  467.  
  468. /**
  469.  * Sets the end transfer function for the file transfer.
  470.  *
  471.  * @param xfer The file transfer.
  472.  * @param fnc  The end transfer function.
  473.  */
  474. void purple_xfer_set_end_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
  475.  
  476. /**
  477.  * Sets the cancel send function for the file transfer.
  478.  *
  479.  * @param xfer The file transfer.
  480.  * @param fnc  The cancel send function.
  481.  */
  482. void purple_xfer_set_cancel_send_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
  483.  
  484. /**
  485.  * Sets the cancel receive function for the file transfer.
  486.  *
  487.  * @param xfer The file transfer.
  488.  * @param fnc  The cancel receive function.
  489.  */
  490. void purple_xfer_set_cancel_recv_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *));
  491.  
  492. /**
  493.  * Reads in data from a file transfer stream.
  494.  *
  495.  * @param xfer   The file transfer.
  496.  * @param buffer The buffer that will be created to contain the data.
  497.  *
  498.  * @return The number of bytes read, or -1.
  499.  */
  500. gssize purple_xfer_read(PurpleXfer *xfer, guchar **buffer);
  501.  
  502. /**
  503.  * Writes data to a file transfer stream.
  504.  *
  505.  * @param xfer   The file transfer.
  506.  * @param buffer The buffer to read the data from.
  507.  * @param size   The number of bytes to write.
  508.  *
  509.  * @return The number of bytes written, or -1.
  510.  */
  511. gssize purple_xfer_write(PurpleXfer *xfer, const guchar *buffer, gsize size);
  512.  
  513. /**
  514.  * Starts a file transfer.
  515.  *
  516.  * Either @a fd must be specified <i>or</i> @a ip and @a port on a
  517.  * file receive transfer. On send, @a fd must be specified, and
  518.  * @a ip and @a port are ignored.
  519.  *
  520.  * @param xfer The file transfer.
  521.  * @param fd   The file descriptor for the socket.
  522.  * @param ip   The IP address to connect to.
  523.  * @param port The port to connect to.
  524.  */
  525. void purple_xfer_start(PurpleXfer *xfer, int fd, const char *ip,
  526.                      unsigned int port);
  527.  
  528. /**
  529.  * Ends a file transfer.
  530.  *
  531.  * @param xfer The file transfer.
  532.  */
  533. void purple_xfer_end(PurpleXfer *xfer);
  534.  
  535. /**
  536.  * Adds a new file transfer to the list of file transfers. Call this only
  537.  * if you are not using purple_xfer_start.
  538.  *
  539.  * @param xfer The file transfer.
  540.  */
  541. void purple_xfer_add(PurpleXfer *xfer);
  542.  
  543. /**
  544.  * Cancels a file transfer on the local end.
  545.  *
  546.  * @param xfer The file transfer.
  547.  */
  548. void purple_xfer_cancel_local(PurpleXfer *xfer);
  549.  
  550. /**
  551.  * Cancels a file transfer from the remote end.
  552.  *
  553.  * @param xfer The file transfer.
  554.  */
  555. void purple_xfer_cancel_remote(PurpleXfer *xfer);
  556.  
  557. /**
  558.  * Displays a file transfer-related error message.
  559.  *
  560.  * This is a wrapper around purple_notify_error(), which automatically
  561.  * specifies a title ("File transfer to <i>user</i> failed" or
  562.  * "File Transfer from <i>user</i> failed").
  563.  *
  564.  * @param type    The type of file transfer.
  565.  * @param account The account sending or receiving the file.
  566.  * @param who     The user on the other end of the transfer.
  567.  * @param msg     The message to display.
  568.  */
  569. void purple_xfer_error(PurpleXferType type, PurpleAccount *account, const char *who, const char *msg);
  570.  
  571. /**
  572.  * Updates file transfer progress.
  573.  *
  574.  * @param xfer      The file transfer.
  575.  */
  576. void purple_xfer_update_progress(PurpleXfer *xfer);
  577.  
  578. /**
  579.  * Displays a file transfer-related message in the conversation window
  580.  *
  581.  * This is a wrapper around purple_conversation_write
  582.  *
  583.  * @param xfer The file transfer to which this message relates.
  584.  * @param message The message to display.
  585.  * @param is_error Is this an error message?.
  586.  */
  587. void purple_xfer_conversation_write(PurpleXfer *xfer, char *message, gboolean is_error);
  588.  
  589. /*@}*/
  590.  
  591. /**************************************************************************/
  592. /** @name UI Registration Functions                                       */
  593. /**************************************************************************/
  594. /*@{*/
  595.  
  596. /**
  597.  * Returns the handle to the file transfer subsystem
  598.  *
  599.  * @return The handle
  600.  */
  601. void *purple_xfers_get_handle(void);
  602.  
  603. /**
  604.  * Initializes the file transfer subsystem
  605.  */
  606. void purple_xfers_init(void);
  607.  
  608. /**
  609.  * Uninitializes the file transfer subsystem
  610.  */
  611. void purple_xfers_uninit(void);
  612.  
  613. /**
  614.  * Sets the UI operations structure to be used in all purple file transfers.
  615.  *
  616.  * @param ops The UI operations structure.
  617.  */
  618. void purple_xfers_set_ui_ops(PurpleXferUiOps *ops);
  619.  
  620. /**
  621.  * Returns the UI operations structure to be used in all purple file transfers.
  622.  *
  623.  * @return The UI operations structure.
  624.  */
  625. PurpleXferUiOps *purple_xfers_get_ui_ops(void);
  626.  
  627. /*@}*/
  628.  
  629. #ifdef __cplusplus
  630. }
  631. #endif
  632.  
  633. #endif /* _PURPLE_FT_H_ */
  634.